# Experiments

The `experiments` configuration enables advanced and experimental capabilities in the plugin.

- Example

```ts
new ModuleFederationPlugin({
  name: '@demo/host',
  experiments: {
    asyncStartup: true,
    externalRuntime: false,
    provideExternalRuntime: false,
    optimization: {
      disableSnapshot: false,
      target: 'web',
    },
  },
  shared: {
    react: {
      singleton: true,
    },
    'react-dom': {
      singleton: true,
    },
  },
  //...
});
```

## asyncStartup

- **Type:** `boolean`
- **Required:** No
- **Default:** `false`

When `asyncStartup` is enabled, all Module Federation entrypoints will initialize asynchronously by default. This means:

- No need for manual `import()` statements at the top of your app (e.g., `import('./bootstrap')`)
- All entrypoints automatically handle async initialization
- Prevention of "eager consumption" errors through automatic async handling

:::warning
When using this mode, all entrypoints will initialize asynchronously. If you're manually requiring a bundled entrypoint or exposing a UMD library, it will return a promise resolving to the exports.
:::

## externalRuntime

- **Type:** `boolean`
- **Required:** No
- **Default:** `false`

After setting `true`, the external MF runtime will be used and the runtime provided by the consumer will be used. (Please make sure your consumer has `provideExternalRuntime: true` set, otherwise it will not run properly!)

## provideExternalRuntime

- **Type:** `boolean`
- **Required:** No
- **Default:** `false`

::: warning note
Make sure to only configure it on the topmost consumer! If multiple consumers inject runtime at the same time, the ones executed later will not overwrite the existing runtime.
:::

Setting `true` will inject the MF runtime at the consumer.

## optimization

This object contains flags related to build-time optimizations that can affect the Module Federation runtime's size and behavior.

### disableSnapshot

- **Type:** `boolean`
- **Required:** No
- **Default:** `false`

When set to `true`, this option defines the `FEDERATION_OPTIMIZE_NO_SNAPSHOT_PLUGIN` global constant as `true` during the build. In the `@module-federation/runtime-core`, this prevents the `snapshotPlugin()` and `generatePreloadAssetsPlugin()` from being included and initialized within the Module Federation instance.

**Impact:**
*   **Benefit:** Can reduce the overall bundle size of the Module Federation runtime by excluding the code for these two plugins.
*   **Cost:** Disables the functionality provided by these plugins. The `snapshotPlugin` is crucial for the "mf-manifest protocol" – it's responsible for generating or providing runtime access to a build manifest (e.g., `mf-manifest.json`) containing metadata about exposed modules, shared dependencies, versions, and remotes. Disabling it means:
    *   The runtime loses access to this build manifest data.
    *   Features relying on the manifest, such as dynamic remote discovery, manifest-based version compatibility checks, advanced asset preloading (also handled by the removed `generatePreloadAssetsPlugin`), and potentially runtime debugging/introspection tools, will not function correctly or will be unavailable.
    *   Use this option only if you do not rely on these manifest-driven features and prioritize a minimal runtime footprint.

:::warning
**Caution:** Setting `disableSnapshot: true` will disable the mf-manifest protocol. This means you will lose TypeScript syncing support and hot module replacement (HMR) for federated modules. If you are only using `.js` remotes (not manifest-based remotes), you will not lose any functionality as the `js` remotes do not support these capabilities anyways.
:::

### target

- **Type:** `'web' | 'node'`
- **Required:** No
- **Default:** Inferred from Webpack's `target` option (usually `'web'`)

This option defines the `ENV_TARGET` global constant during the build, specifying the intended execution environment.

**Impact:**
*   **`target: 'web'`**: Optimizes the build for browser environments.
    *   Ensures browser-specific remote entry loading mechanisms are used (`loadEntryDom`).
    *   Crucially, enables tree-shaking/dead-code elimination for Node.js-specific code within the `@module-federation/sdk`. Functions like `createScriptNode` and `loadScriptNode`, along with their required Node.js built-in modules (e.g., `vm`, `path`, `http`), are completely removed from the bundle, significantly reducing its size.
*   **`target: 'node'`**: Optimizes the build for Node.js environments.
    *   Ensures Node.js-specific remote entry loading mechanisms are used (`loadEntryNode`).
    *   Includes the necessary Node.js-specific functions from the SDK (`createScriptNode`, `loadScriptNode`) in the bundle, allowing the federated application to function correctly in Node.js.

Explicitly setting this value is recommended to ensure the intended optimizations are applied, especially in universal or server-side rendering scenarios.

### Impact of Optimization Flags on `remoteEntry.js` Size

The following table demonstrates how different combinations of the `disableSnapshot`, `target: 'web'`, and `externalRuntime` optimization flags affect the size of the generated `remoteEntry.js` file. These measurements can help you choose the right trade-off between runtime features and bundle size for your use case.

| Optimization Flags                          | remoteEntry.js | Gzip Size | Brotli Size |
|---------------------------------------------|:--------------:|:---------:|:-----------:|
| No optimization flags enabled               | 69K            | 21437 B   | 19024 B     |
| `disableSnapshot: true`                     | 65K            | 20096 B   | 17860 B     |
| `target: 'web'`                             | 60K            | 19314 B   | 17105 B     |
| Both enabled                                | 56K            | 17998 B   | 15982 B     |
| Both enabled + `externalRuntime: true`      | 14K            | 5381 B    | 4703 B      |
| Both disabled + `externalRuntime: true`     | 22K            | 8222 B    | 7269 B      |

**Notes:**
- Enabling both `disableSnapshot` and `target: 'web'` provides the greatest reduction in bundle size, especially when combined with `externalRuntime: true`.
- Using the external runtime (`externalRuntime: true`) can dramatically reduce the size of your remote entry, but requires that the consumer provides the runtime.
- Smaller bundle sizes can lead to faster load times and improved performance, but may disable certain features (see above for details on what each flag does).
